LD

NAME

SYNOPSIS

DESCRIPTION

FAT FILE SUPPORT

The compiler driver cc(1) handles creating fat executables by calling ld(1) multiple times and using lipo(1) to create a ``fat'' file from the results of the ld(1) executions.  

OUTPUT FILE LAYOUT

The object files are loaded in the order in which they are specified on the command line. The segments and the sections in those segments will appear in the output file in the order they are encountered in the object files being linked. All zero fill sections will appear after all non-zero fill sections in their segments.

Sections created from files with the -sectcreate option will appear in the output file last. Section names for sections created from files are not allowed to overlap with a section name in the same segment as a section coming from an object file. Sections created from files may be in a segment which has sections from object files and if so will be loaded at the end of the non-zero fill sections for that segment.

If the option -seglinkedit is specified, the segment it creates is the last segment in the output file.

The address of each segment can be specified with -segaddr, which takes the segment's name as an argument. The address of the first segment can alternatively be specified using -seg1addr, in which case a segment name is not used. Segments that do not have a specified address will be assigned addresses in the order in which they appear in the output file. A segment's address will be assigned based on the ending address of the previous segment. If the address of the first segment has not been specified by name, its assigned address will be the specified (via -seg1addr) or default first segment address. If neither flag is used to specify the first segment's address, its default address is zero for all formats except the demand-paged executable format (MH_EXECUTE), in which case the default first address is the value of the segment alignment.

For demand-paged executable format (MH_EXECUTE) output files, if none of the segments' addresses covers address zero through the value of the segment alignment, a segment with no access protection will be created to cover those addresses. This segment, named ``__PAGEZERO'', is created so that any attempt to dereference a NULL pointer will cause a memory exception.

The entry point of the output file is the beginning of the first section in the first segment (unless the -e option is specified).  

LIBRARIES

If any argument is a library, it is searched exactly once at the point it is encountered in the argument list. Only those members defining an unresolved external reference, as defined by the table of contents of the library, are loaded. Library members can also be loaded in response to the -ObjC and -all_load flags (see their descriptions below). All libraries must be processed by ranlib(1) to produce a table of contents for the library.

Generally, a library does not have multiple members that define the same symbol. In this case, the order of the members is not important, so the table of contents can be sorted by symbol name via the -s option to ranlib(1), which speeds the resulting link editing. The first member of the library will be a file named ``__.SYMDEF SORTED'', which is understood to be a sorted table of contents.

However, if the library does have multiple members that define the same symbol, the table of contents that ranlib(1) produces can't be sorted. Instead, it follows the order in which the members appear in the library. The link editor searches the table of contents iteratively, loading members until no further references are satisfied. In this unsorted case, the first member of the library will be a file named ``__.SYMDEF'', which is understood to be a table of contents in the order of the archive members.

LINK EDITOR DEFINED SYMBOLS

There is a group of link editor defined symbols for the MH_EXECUTE and MH_PRELOAD file types, but none for the other file types. Link editor symbols are reserved; it is an error if an input object file defines such a symbol. Only those link editor symbols that are referenced by the object file appear in the output file's symbol table.

The link editor defined symbol `__mh_execute_header' (`_mh_execute_header' in C) is reserved when the output file format is MH_EXECUTE. This symbol is the address of the Mach header in a Mach-O executable (a file of type MH_EXECUTE). It does not appear in any other Mach-O file type. It can be used to get to the addresses and sizes of all the segments and sections in the executable, as well as any shared libraries it uses. This can be done by parsing the headers and load commands (see Mach-O(5)).

The MH_PRELOAD file type has link editor defined symbols for the beginning and ending of each segment, and for the beginning and ending of each section within a segment. These names are provided for use in a Mach-O preloaded file, since it does not have its headers loaded as part of the first segment. The names of the symbols for a segment's beginning and end have the form: __SEGNAME__begin and __SEGNAME__end, where __SEGNAME is the name of the segment. Similarly, the symbols for a section have the form: __SEGNAME__sectname__begin and __SEGNAME__sectname__end, where __sectname is the name of the section in the segment __SEGNAME. These symbols' types are those of the section that the names refer to. (A symbol that refers to the end of a section actually has, as its value, the beginning address of the next section, but the symbol's type is still that of the section mentioned in the symbol's name.)  

OPTIONS

Ld understands several options. Filenames and options that refer to libraries (such as -l), as well as options that create symbols (such as -u and -i), are position-dependent: They define the load order and affect what gets loaded from libraries.

The most common option is:

-o name

The output file is named name, instead of a.out.

The following flags are related to architectures:

-arch arch_type

Specifies the architecture, arch_type, for the output file. ``Fat'' input files that do not contain this specified architecture are ignored. Only one -arch arch_type can be specified. See arch(3) for the currently known arch_types. If arch_type specifies a certain implementation of an architecture (such as -arch m68040 or -arch i486 ), the resulting object file has that specific CPU subtype, and it is an error if any input file has a CPU subtype that will not combine to the CPU subtype for arch_type.

The default output file architecture is determined by the first object file to be linked. If it is a ``thin'' (standard Mach-O) file, or a ``fat'' file that contains only one architecture, the output file will have the same architecture. Otherwise, if it is a ``fat'' file containing an architecture that would execute on the host, then the ``best'' architecture is used, as defined by what the kernel exec(2) would select. Otherwise, it is an error, and a -arch arch_type must be specified.

-arch_multiple

This flag is used by the cc(1) driver program when it is run with multiple -arch arch_type flags. It instructs programs like ld(1) to precede any displayed message with a line stating the program name, in this case ld, and the architecture (from the -arch arch_type flag). This helps distinguish which architecture the error messages refer to.

-force_cpusubtype_ALL

The -force_cpusubtype_ALL flag causes the CPU subtype to remain the ALL CPU subtype and not to be combined or changed. This flag has precedence over any -arch arch_type flag for a specific implementation.

The following flags are related to libraries:

-lx

This option is an abbreviation for the library name `libx.a', where x is a string. Ld searches for libraries first in any directories specified with -L options, then in the standard directories /lib, /usr/lib, and /usr/local/lib. A library is searched when its name is encountered, so the placement of the -l flag is significant. If string x is of the form x.o, then that file is searched for in the same places, but without prepending `lib' or appending `.a' to the filename.

-Ldir

Add dir to the list of directories in which to search for libraries. Directories specified with -L are searched before the standard directories.

-Z

Do not search the standard directories when searching for libraries.

-ObjC

Cause the correct Objective C semantics when loading a library. This causes all library members that define an Objective C class or a category to be loaded.

-all_load

Cause all library members to be loaded.

The following options specify the output file format (the file type):

-execute

Produce a Mach-O demand-paged executable format file. The headers are placed in the first segment, and all segments are padded to the segment alignment. This has a file type of MH_EXECUTE. This is the default. If no segment address is specified at address zero, a segment with no protection (no read, write, or execute permission) is created at address zero. This segment, whose size is that of the segment alignment, is named ``__PAGEZERO''. This option was previously named -Mach, which will continue to be recognized.

-object

Produce a Mach-O file in the the relocatable object file format that is intended for execution. This differs from using the -r option in that it defines common symbols, does not allow undefined symbols and does not preserve relocation entries. This has a file type of MH_OBJECT. In this format all sections are placed in one unnamed segment with all protections (read, write, execute) allowed on that segment. This is intended for extremely small programs that would otherwise be large due to segment padding. In this format, and all non-MH_EXECUTE formats, the link editor defined symbol ``__mh_execute_header'' is not defined since the headers are not part of the segment.

-preload

Produce a Mach-O preloaded executable format file. The headers are not placed in any segment. All sections are placed in their proper segments and they are padded to the segment alignment. This has a file type of MH_PRELOAD. This option was previously -p, which will continue to be recognized.

-fvmlib

Produce a Mach-O fixed VM shared library format file. The headers are placed in the first segment but the first section in that segment will be placed on the next segment alignment boundary in that segment. All sections are placed in their proper segments and they are padded to the segment alignment. This has a file type of MH_FVMLIB.

The following flags affect the contents of the output file:

-r

Save the relocation information in the output file so that it can be the subject of another ld run. The resulting file type is a Mach-O relocatable file (MH_OBJECT) if not otherwise specified. This flag also prevents final definitions from being given to common symbols, and suppresses the `undefined symbol' diagnostics.

-d

Force definition of common storage even if the -r flag is present. This also forces link editor defined symbols to be defined.

The following flags support segment specifications:

-segalign value

Specifies the segment alignment. value is a hexadecimal number that must be an integral power of 2. The default is the target pagesize (2000 hex currently).

-seg1addr addr

Specifies the starting address of the first segment in the output file. addr is a hexadecimal number and must be a multiple of the segment alignment.

-segaddr name addr

Specifies the starting address of the segment named name to be addr. The address must be a hexadecimal number that is a multiple of the segment alignment.

-segprot name max init

Specifies the maximum and initial virtual memory protection of the named segment, name, to be max and init respectfully. The values for max and init are any combination of the characters `r' (for read), `w' (for write), `x' (for execute) and '-' (no access). The default is `rwx' for the maximum and initial protection for all segments except for the ``__TEXT'' segment. The latter, if it exists, has an initial protection of `rx' (not writable).

-seglinkedit

Create the link edit segment, named ``__LINKEDIT'' (this is the default). This segment contains all the link edit information (relocation information, symbol table, string table, etc.) in the object file. If the segment protection for this segment is not specified, the initial protection is not writable. This can only be specified for the MH_EXECUTE and MH_FVMLIB output file types. To get at the contents of this section, the Mach header and load commands must be parsed from the link editor defined symbol `__mh_execute_header' (see Mach-O(5)).

-noseglinkedit

Do not create the link edit segment (see -seglinkedit above).

-pagezero_size value

Specifies the segment size of __PAGEZERO to be of size value, where value is a hexadecimal number rounded to the segment alignment. The default is the target pagesize (currently, 2000 hexadecimal).

The following flags support section specifications:

-sectcreate segname sectname file

The section sectname in the segment segname is created from the contents of file. The combination of segname and sectname must be unique; there cannot already be a section (segname,sectname) in any input object file. This option was previously called -segcreate, which will continue to be recognized.

-sectalign segname sectname value

The section named sectname in the segment segname will have its alignment set to value, where value is a hexadecimal number that must be an integral power of 2. This can be used to set the alignment of a section created from a file, or to increase the alignment of a section from an object file, or to set the maximum alignment of the (__DATA,__common) section, where common symbols are defined by the link editor. Setting the alignment of a literal section causes the individual literals to be aligned on that boundary. If the section alignment is not specified by a section header in an object file or on the command line, it defaults to 10 (hex), indicating 16-byte alignment.

-sectorder segname sectname orderfile

The section sectname in the segment segname of the input file will be broken up into blocks associated with symbols in the section. The output section will be created by ordering the blocks as specified by the lines in the orderfile. These blocks are aligned to the output file's section alignment for this section. Any section can be ordered in the output file.

For non-literal sections, each line of the orderfile contains an object name and a symbol name, separated by a single colon (':'). If the object file is in an archive, the archive name, followed by a single colon, must precede the object file name. The object file names and archive names should be exactly the names as seen by the link editor, but if not, the link editor attempts to match up the names the best it can. For non-literal sections, the easiest way to generate an order file is with the ``-jonls segname sectname'' options to nm(1).

The format of the orderfile for literal sections is specific to each type of literal section. For C string literal sections, each line of the order file contains one literal C string, which may include ANSI C escape sequences. For four-byte literal sections, the order file format is one 32-bit hex number with a leading 0x per line, with the rest of the line treated as a comment. For eight-byte literal sections, the order file has two 32-bit hex numbers per line; each number has a leading 0x, the two numbers are separated by white space, and the rest of the line is treated as a comment. For literal pointer sections, the lines in the order file represent pointers, one per line. A literal pointer is represented by the name of the segment that contains the literal being pointed to, followed by the section name, followed by the literal. These three strings are separated by colons with no extra white space. For all the literal sections, each line in the the order file is simply entered into the literal section and will appear in the output file in the same order as in the order file. There is no check to see whether the literal is present in the loaded objects. For literal sections, the easiest way to generate an order file is with the ``-X -v -s segname sectname'' options to otool(1). For detailed information, see ``Link Optimization'' in the ``Performance'' section of the NEXTSTEP Concepts manual.

-sectorder_detail

When using the -sectorder option, any pairs of object file names and symbol names that are found in the loaded objects, but not specified in the orderfile, are placed last in the output file's section. These pairs are ordered by object file (as the filenames appear on the command line), with the different symbols from a given object file being ordered by increasing symbol address (that is, the order in which the symbols occurred in the object file, not their order in the symbol table). By default, the link editor displays a summary that simply shows the number of symbol names found in the loaded objects but not in the orderfile, as well as the number of symbol names listed in the orderfile but not found in the loaded objects. (The summary is omitted if both values are zero.) To instead produce a detailed list of these symbols, use the -sectorder_detail flag. If an object file-symbol name pair is listed multiple times, a warning is generated, and the first occurrence is used.

-sectobjectsymbols segname sectname

This causes the link editor to generate local symbols in the section sectname in the segment segname. Each object file that has one of these sections will have a local symbol created whose name is that of the object file, or of the member of the archive. The symbol's value will be the first address where that object file's section was loaded. The symbol has the type N_SECT and its section number is the the same as that of the section (segname,sectname) in the output file. This symbol will placed in the symbol table just before all other local symbols for the object file. This feature is typically used where the section is (__TEXT,__text), in order to help the debugger debug object files produced by old versions of the compiler or by non-NeXT compilers.

The following flags are related to symbols. These flags' arguments are external symbols whose names have `_' prepended to the C, FORTRAN, or Pascal variable name.

-ysym

Display each file in which sym appears, its type, and whether the file defines or references it. Any multiply defined symbols are automatically traced. Like most of the other symbol-related flags, -y takes only one argument; the flag may be specified more than once in the command line to trace more than one symbol.

-m

Don't treat multiply defined symbols as a hard error; instead, simply print a warning. The first such symbol is used for linking; its value is used for the symbol in the symbol table. The other symbols by the same name may be used in the resulting output file through local references. This can still produce a resulting output file that is in error. This flag's use is strongly discouraged!

-whyload

Indicate why each member of an archive is loaded. In other words, indicate which currently undefined symbol is being resolved, causing that archive member to be loaded. This in combination with the above -ysym flag can help determine exactly why a link edit is failing due to multiply defined symbols.

-u sym

Enter the argument sym into the symbol table as an undefined symbol. This is useful for loading wholly from a library, since initially the symbol table is empty and an unresolved reference is needed to force the loading of the first object file.

-e sym

The argument sym is taken to be the symbol name of the entry point of the resulting file. By default, the entry point is the address of the first section in the first segment.

-idefinition:indirect

Create an indirect symbol for the symbol name definition which is defined to be the same as the symbol name indirect (which is taken to be undefined). When a definition of the symbol named indirect is linked, both symbols will take on the defined type and value.

-U sym

Allow the symbol sym to be undefined, even if the -r flag is not given. Produce an executable file if the only undefined symbols are those specified with -U.

The following flags are related to stripping link edit information. This information can also be removed by strip(1), which uses the same options. (The exception is the -s flag below, but this is the same as strip(1) with no arguments.) The following flags are listed in decreasing level of stripping.

-s

Completely strip the output; that is, remove the symbol table and relocation information.

-x

Strip the non-global symbols; only save external symbols.

-S

Strip debugging symbols; only save local and global symbols.

-X

Strip local symbols whose names begin with `L'; save all other symbols. (The compiler and assembler currently strip these internally-generated labels by default, so they generally do not appear in object files seen by the link editor.)

-b

Strip the base file's symbols from the output file. (The base file is given as the argument to the -A option.)

The remaining options are infrequently used:

-w

Inhibit all warning messages.

-M

Produce a load map, listing all the segments and sections. The list includes the address where each input file's section appears in the output file, as well as the section's size.

-whatsloaded

Display a single line listing each object file that is loaded. Names of objects in archives have the form libfoo.a(bar.o).

-headerpad value

Specifies the minimum amount of space ("padding") following the headers for the MH_EXECUTE format. value is a hexadecimal number. When a segment's size is rounded up to the segment alignment, there is extra space left over, which is placed between the headers and the sections, rather than at the end of the segment. The headerpad option specifies the minimum size of this padding, which can be useful if the headers will be altered later. The default is to use the amount of the first segment's round-off as the minimum padding for all segments. (That is, take the total size of the first segments' headers and non-zerofill sections, round this size up to the segment alignment, and use the difference between the rounded and unrounded sizes as the minimum amount of padding.)

-t

Trace the progress of the link editor; display the name of each file that is loaded as it is processed in the first and second pass of the link editor.

-A basefile

Incremental loading: linking is to be done in a manner that lets the resulting object be read into an already executing program, the basefile. basefile is the name of a file whose symbol table will be taken as a basis on which to define additional symbols. Only newly linked material will be entered into the a.out file, but the new symbol table will reflect every symbol defined in the base file and the newly linked files. Option(s) to specify the addresses of the segments are typically needed, since the default addresses tend to overlap with the basefile. The default format of the object file is MH_OBJECT. Note: It is strongly recommended that this option NOT be used, because the rld package described in rld(3) is a much easier alternative.

Options available in early versions of the Mach-O link editor may no longer be supported.

FILES

SEE ALSO

Index

NAME

SYNOPSIS

DESCRIPTION

FAT FILE SUPPORT

OUTPUT FILE LAYOUT

LIBRARIES

LINK EDITOR DEFINED SYMBOLS

OPTIONS

FILES

SEE ALSO